home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / mac / misc / update / 4dext.cpt / 4DtoResourceto4D 1.0.1 / 4D<->Resources Docs next >
Encoding:
Text File  |  1992-05-19  |  7.9 KB  |  173 lines
  1. 4D<->Resources Externals
  2. by Robert Hess
  3. ⌐1992, ENDPOINT! Marketing Information Systems
  4. Sunnyvale, CA (408)╩733╨4908
  5. AppleLink: ENDPOINT
  6. CIS: 71641,1376
  7. Internet: endpoint@applelink.apple.com or rhessjr@west.darkside.com or
  8. rhessjr@aol.com
  9. America Online: RHessJr
  10. QM-to-QM: Robert Hess, (408) 738-0830 (1200 baud)
  11.  
  12. Legalese BS From Hell
  13. =====================
  14. These externals may not be used in any way in any commercial or for-profit
  15. database/program/endeavor without the written consent of ENDPOINT!. The author
  16. does not warranty these externals in any way, nor does ENDPOINT!; use them at
  17. your own risk. The externals may be redistributed only as a united pair and
  18. only when included with this documentation file. The externals may not be
  19. included as a part of any collection of software including (but not restricted
  20. to only) collections of shareware/freeware/demoware/etc. for which a charge is
  21. applied without previous written consent of the author. The only exception
  22. which requires no previous written consent is distribution via America Online,
  23. CompuServe, GEnie, BIX, Internet, AppleLink, private BBSes or other
  24. telecommunicative services which charge only for online time but not for
  25. individual pieces of collections of software.
  26.  
  27. Not with that garbage out of the way...
  28.  
  29.  
  30. The included PROC.EXTs contain two externals: 4DtoResource and Resourceto4D.
  31. They accomplish opposing (complimentary?) functions. 4DtoResource takes a 4D
  32. variable and copies its contents into a resource file (actually, into a file╒s
  33. resource fork as a valid resource); Resourceto4D copies the contents of a
  34. resource in a file╒s resource fork and passes it into a 4D text variable.
  35.  
  36. ------------------
  37. Resourceto4D(&T;&S;&I;&S;&T):I
  38. &T=Pathname to the file to be opened for resource reading
  39. &S=four-character resource type to be opened
  40. &I=resource ID to be opened
  41. &S=resource Name to be opened
  42. &T=the variable which will be filled with the read resource╒s data
  43.  
  44. Example 1:
  45. C_TEXT(gData)
  46. C_INTEGER(error)
  47. error:=0
  48. gData:=""
  49. error:=Resourceto4D("D80:TestFile";"DATA";128;"";gData)
  50.  
  51. After execution, the variable ╥gData╙ would contain the contents of resource
  52. DATA #128 (which has no name) contained in the file ╥TestFile╙ on volume
  53. ╥HD80╙.
  54.  
  55. The path may include imbedded folders but may not exceed 255 characters. If
  56. you exceed 255 characters, I will return an error -193 (╥Resource File Not
  57. Found╙) to you. The path may not end in a colon; this would indicate that I
  58. should open the resource fork of a folder. Bad idea.
  59.  
  60. The four-character type may be anything you wish, which is the whole idea,
  61. allowing the access to custom resources designed and added by the programmer.
  62. Passing more than four characters isn╒t advised.
  63.  
  64. The resource ID must be an integer, obviously. Even if you want to access ID
  65. zero, you should declare this as equal to ╥0╙.
  66.  
  67. The name may be passed as Null ("") to indicate a resource without a name.
  68. NAME TAKES PRECEDENCE. In other words, if you call
  69. Resourceto4D($myFile;"DATA";128;"Stimpy";gData), I will go looking for a
  70. resource of type DATA with the name ╥Stimpy╙; I will ignore the resource ID
  71. number 128. If you pass a name, therefore, it really doesn╒t matter what you
  72. put in the third parameter (pass a zero, for example).
  73.  
  74. The final parameter must be of type Text. I will pass the data from the
  75. resource directly back to you unaffected; it╒s up to you to decide what to do
  76. with it. You should declare this variable as blank/null/empty prior to calling
  77. the external. Since a resource cannot exceed 32K, a text resource should
  78. always be able to handle any resource.
  79.  
  80. ------------------
  81. 4DtoResource(&T;&S;&I;&S;&T):I
  82.  
  83. Example 2:
  84. C_TEXT(gData)
  85. C_INTEGER(error)
  86. error:=0
  87. gData:="myDATAisBETTERthanYOURdata"
  88. error:=Resourceto4D("HD80:TestFile";"DATA";128;"MyResource";gData)
  89.  
  90. All parameters are the same except that the final Text variable should contain
  91. the data which you wish to have written into the specified resource. You may
  92. pass an empty string; this will save the resource type specified, but as
  93. empty.
  94.  
  95. Additionally, whereas the fourth parameter is highly important in
  96. Resourceto4D, it is entirely optional in 4DtoResource. This is because I save
  97. the resource type and ID (which are mandatory), and then toss the resource
  98. name onto the saved resource. It may be passed as Null ("") if you don╒t care
  99. to name the resource. Remember: there╒s nothing to stop you from saving
  100. several resources with the same resource name; it╒s a lousy idea for you to do
  101. it (because it makes accessing them by name unreliable), but I let you do it.
  102.  
  103. If you specify an existing resource type and ID, it will be completely
  104. overwritten. In fact, prior to saving the resource you specify, I delete any
  105. existing resource with that type and ID/name (whether or not I should save the
  106. new resource under a unique ID, delete the original and then renumber the new
  107. copy is debatable; it╒s more time-consuming and, practically, no safer since
  108. you would have to stop what you were doing and fix the problem prior to using
  109. the file...not something you would commonly be able to do from within 4D).
  110.  
  111. You may pass literal data in place of gData above but I don╒t suggest it since
  112. it╒s more likely that 4D will properly coerce it if you have compiler-directed
  113. the variable to text.
  114.  
  115. Trivia Note: why are the externals called what they are? I originally wanted
  116. to call them ╥GetResource╙ and ╥PutResource╙ or ╥ReadResource╙ and
  117. ╥WriteResource╙. Unfortunately, ╥GetResource╙ and ╥WriteResource╙ are reserved
  118. names (why the heck did one from each pair get chosen? You╒ve got me╔Apple
  119. programmers are a Mountain Dew drunk lot╔) and pairing ╥PutResource╙ with
  120. ╥ReadResource╙ seemed awkward; so ╥4DtoResource╙ and ╥Resourceto4D╙ were
  121. born╔Actually, in C, having a procedure named with a number as its first
  122. character is a no-no, so it╒s really called ╥FourDtoResource"╔I╒m going to
  123. bed╔
  124.  
  125. Note: When you pass me the pathname, I open that file (if it exists), access
  126. it and close it. Therefore, those of you using my externals and hoping that I
  127. leave the file open should not assume this; I restore the current resource
  128. file to what it was prior to your calling the externals. (If that doesn╒t make
  129. sense to you, don╒t worry about it. Only programmer geeks care about it. ;)
  130.  
  131. So, what do I want for this? NADA. Not a darn thing. Well, OK, you can do two
  132. things:
  133.  
  134. 1) Write me a letter (electronically, preferably) or call me and tell me what
  135. you╒r doing with the external...or, better yet, what other cool stuff you╒d
  136. like to see me do. (I╒m one of those sick fools who hears, ╥Wouldn╒t it be
  137. cool if...╙ and ends up spending the next three weeks doing it.
  138.  
  139. 2) Get involved in the leadership of this country. VOTE, damn it. Or, even
  140. better, run for office. The more level-headed, reality-based, non-professional
  141. politicians we have, the more likely I╒ll have a decent world in which to
  142. raise my kids. Then again, knowing what most 4D users are like, maybe we
  143. should stay out of politics...
  144.  
  145. (OK, I lied...there are two materialistic things I╒d like. If you happen to
  146. own an original cell of Ren & Stimpy, I╒d love it. Or you could pay for me to
  147. take a C class to become a better programmer. I╒d even name these externals
  148. after you. Just think: people worldwide would be calling
  149. ╥Resourceto4DSylvesterAnderson╙, cursing both of us for the stupid external
  150. name. ;)
  151.  
  152.  
  153. Version History:
  154. ----------------
  155. 0.0.1: Initial ╥release╙.
  156.  
  157.  
  158. 0.0.2: BUG FIX: There was a bug in 4DtoResource 0.0.1 whereby the saving of a
  159. non-existant resource failed (in other words, if you did a
  160. 4DtoResource(╙HD80:File╙;╙DATA╙;128;gData) and DATA #128 didn╒t already exist
  161. in HD80:File, the resource would not be created. This works now. I have
  162. properly berated myself...
  163.  
  164. NEW FEATURE: You have access to resource names now. RE-READ THE DOCS IF YOU
  165. HAVEN╒T ALREADY! I changed the way that you must call the externals from 0.0.1
  166. to support resource names.
  167.  
  168.  
  169. 1.0.0: I do a better FlushVol now. First "release" version.
  170.  
  171.  
  172. 1.0.1: If you tried to save a resource to a non-existant file (or an existant
  173. one which had no resource fork), you got an error. No longer.